Skip to content

FOUR-34335: Add Responder Tracking and Personalized Email Links for Actions by Email - #9169

Open
sanjacornelius wants to merge 20 commits into
developfrom
subtask/FOUR-34335
Open

sanjacornelius wants to merge 20 commits into
developfrom
subtask/FOUR-34335

Conversation

@sanjacornelius

@sanjacornelius sanjacornelius commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

This PR adds optional responder tracking for ABE, allowing the system to track which recipient clicked and completed an email action. When enabled, each recipient receives a personalized signed link and responder information is captured in request data. This work also introduces staggered email delivery to help reduce provider rate limiting and preserves responder tracking through Require Login scenarios.

Changes:

  • Added optional responder tracking controlled by the trackResponder setting.
  • Sends one personalized email per unique recipient when responder tracking is enabled.
  • Continues using a single shared email when responder tracking is disabled.
  • Adds signed responder information to action links:
    - abe_email
    -abe_user_id
    - abe_groups
    - abe_sig
  • Captures responder details in a nested abe_responder object within request data.
  • Added support for preserving signed ABE parameters through Require Login using abe_click_ticket.
  • Detects forwarded email scenarios where a different user authenticates and records:
    - email
    - authenticated_email
    - identity_mismatch
  • Action execution continues even when an identity mismatch is detected.
  • Added configurable email dispatch staggering via abe_email_stagger_seconds to reduce provider throttling and rate limiting.
  • Merges group memberships when recipients belong to overlapping groups or shared inboxes to prevent duplicate sends.
  • Added documentation:
    - docs/abe-responder-tracking.md

Dependencies:

How to Test

Responder Tracking Disabled

  1. Configure an ABE task with Track Responder Identity disabled.
  2. Send the email.
  3. Verify only one shared email is sent.
  4. Complete the action from the email link.
  5. Verify no abe_responder data is written to the request

Responder Tracking Enabled

  1. Configure an ABE task with Track Responder Identity enabled.
  2. Send the email to multiple recipients.
  3. Verify each unique recipient receives their own email.
  4. Verify action links contain signed responder parameters:
    • abe_email
    • abe_user_id
    • abe_groups
    • abe_sig
  5. Complete the action from an email link.
  6. Verify request data contains a populated abe_responder object.

Request Data Validation

  1. Complete an ABE action using a signed link.
  2. Verify responder information is stored under abe_responder.
  3. Verify responder data is not written to top-level fields such as:
    • user_id
    • acted_at

Group Deduplication

  1. Create a user that belongs to multiple groups receiving the same email.
  2. Trigger the ABE task.
  3. Verify only one email is sent to that user.
  4. Verify group information is merged correctly within the signed payload.

Large Recipient Groups

  1. Configure an ABE task targeting a large user group.
  2. Trigger email delivery.
  3. Verify emails are queued with staggered delays.
  4. Monitor email provider activity and verify no unexpected throttling or rate-limit failures occur.

Require Login / Forwarded Email Scenario

  1. Enable Require Login.
  2. Send an ABE email to User A.
  3. Forward the email to User B.
  4. Open the email in a private/incognito session.
  5. Authenticate as User B.
  6. Complete the action.
  7. Verify:
    • email contains User A's email.
    • authenticated_email contains User B's email.
    • identity_mismatch is set to true
  8. Verify the action completes successfully.

Related Tickets & Packages

ci:connector-send-email:subtask/FOUR-34335
ci:package-actions-by-email:subtask/FOUR-34335
ci:deploy

Code Review Checklist

  • I have pulled this code locally and tested it on my instance, along with any associated packages.
  • This code adheres to ProcessMaker Coding Guidelines.
  • This code includes a unit test or an E2E test that tests its functionality, or is covered by an existing test.
  • This solution fixes the bug reported in the original ticket.
  • This solution does not alter the expected output of a component in a way that would break existing Processes.
  • This solution does not implement any breaking changes that would invalidate documentation or cause existing Processes to fail.
  • This solution has been tested with enterprise packages that rely on its functionality and does not introduce bugs in those packages.
  • This code does not duplicate functionality that already exists in the framework or in ProcessMaker.
  • This ticket conforms to the PRD associated with this part of ProcessMaker.

@cursor

cursor Bot commented Nov 15, 2026 •

Copy link
Copy Markdown

PR Summary

Medium Risk
Opt-in email and task-click flow changes affect authentication redirects, request data shape, and bulk send volume; legacy ABE remains the default when trackResponder is disabled.

Overview
Adds optional Track responder identity for Actions by Email: when trackResponder is on in configEmail, the system resolves unique recipients (deduping emails and merging overlapping groups), sends one personalized email per address with HMAC-signed query params on /tasks/update_variable/ links, and on click stores a nested abe_responder object in request data (signed recipient, click metadata, and optional identity_mismatch vs the logged-in user). Legacy behavior is unchanged when tracking is off (single shared email, no abe_responder).

Require Login no longer loses signed params: the full click query is cached under an abe_click_ticket cookie (unencrypted) and merged back in updateVariable before validation. Email sends can be staggered via abe_email_stagger_seconds to reduce provider rate limits.

Reviewed by Cursor Bugbot for commit 6a4fa3e. Bugbot is set up for automated code reviews on this repo. Configure here.

@cursor cursor Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cursor Bugbot has reviewed your changes using high effort and found 2 potential issues.

Fix All in Cursor

❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.

Want fixes drafted automatically? Bugbot Autofix can create code changes for findings. A team admin can enable Autofix in the Cursor dashboard.

Reviewed by Cursor Bugbot for commit 6a4fa3e. Configure here.

Comment thread ProcessMaker/Mail/TaskActionByEmail.php Resolved
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant